/// <summary>
/// An <see cref="ObjectPool{T}"/> backed by a shared <see cref="IMemoryCache"/>,
/// capable of holding multiple instances of the same type simultaneously.
/// </summary>
/// <typeparam name="T">The type of objects being pooled.</typeparam>
/// <remarks>
/// <para>
/// Instances are stored under composite keys of <c>(_poolId, index)</c> where
/// <c>_poolId</c> is a unique identifier per pool instance and <c>index</c> is a
/// monotonically increasing stack pointer. This avoids key collisions when
/// multiple pools share the same <see cref="IMemoryCache"/>.
/// </para>
/// <para>
/// <see cref="Get"/> walks the stack from the top down using
/// <see cref="Interlocked.Decrement"/> and returns the first entry still present
/// in the cache (last-in-first-out). Because cache eviction always discards
/// older entries first, any gap near the top implies all entries below have also
/// been evicted, so the walk terminates early. On a complete miss the pool
/// falls back to <see cref="IPooledObjectPolicy{T}.Create"/>.
/// </para>
/// <para>
/// <see cref="Return"/> evaluates <see cref="IPooledObjectPolicy{T}.Return"/>
/// and <see cref="IResettable.TryReset"/> before storing; if either rejects the
/// instance it is disposed immediately. Accepted instances are pushed onto the
/// stack via <see cref="Interlocked.Increment"/> and stored in the cache with a
/// post-eviction callback that disposes the instance when the cache drops it.
/// </para>
/// <para>
/// This pool does not own the <see cref="IMemoryCache"/> — the cache is
/// provided by and disposed by the container. The pool only owns the pooled
/// instances themselves.
/// </para>
/// </remarks>
public sealed class CacheObjectPool<T> : ObjectPool<T>, IDisposable
    where T : class
{
    private readonly IMemoryCache _cache;
    private readonly IPooledObjectPolicy<T> _policy;
    private readonly MemoryCacheEntryOptions _options;
    private readonly string _poolId;
    private int _top;
    private bool _disposed;

    /// <summary>
    /// Initializes a new instance of the <see cref="CacheObjectPool{T}"/> class.
    /// </summary>
    /// <param name="cache">
    /// The shared memory cache. All pools that share this cache also share its
    /// eviction budget.
    /// </param>
    /// <param name="policy">
    /// The policy Autofac supplies. Its <see cref="IPooledObjectPolicy{T}.Create"/>
    /// resolves a fully-injected instance through the container; its
    /// <see cref="IPooledObjectPolicy{T}.Return"/> fires the pooling callbacks.
    /// </param>
    /// <param name="options">
    /// Optional cache entry options. When <see langword="null"/> a default with
    /// a five-minute sliding expiration and a post-eviction disposal callback
    /// is used.
    /// </param>
    /// <exception cref="ArgumentNullException">
    /// Thrown when <paramref name="cache"/> or <paramref name="policy"/> is
    /// <see langword="null"/>.
    /// </exception>
    public CacheObjectPool(
        IMemoryCache cache,
        IPooledObjectPolicy<T> policy,
        MemoryCacheEntryOptions? options = null)
    {
        ArgumentNullException.ThrowIfNull(cache);
        ArgumentNullException.ThrowIfNull(policy);

        _cache = cache;
        _policy = policy;
        _options = WithEvictionCallback(
            options ?? new MemoryCacheEntryOptions
            {
                SlidingExpiration = TimeSpan.FromMinutes(5)
            });
        _poolId = Guid.NewGuid().ToString("N");
        _top = -1;
    }

    /// <summary>
    /// Retrieves an instance from the pool.
    /// </summary>
    /// <returns>
    /// A pooled instance if one is available in the cache, otherwise a new
    /// instance created through <see cref="IPooledObjectPolicy{T}.Create"/>
    /// (and therefore through the Autofac container).
    /// </returns>
    /// <remarks>
    /// The pool walks its LIFO stack from the top down via
    /// <see cref="Interlocked.Decrement"/>, returning the first cache hit.
    /// Because <see cref="IMemoryCache"/> evicts older entries first, a miss
    /// near the top implies all entries below have also been evicted, so the
    /// walk terminates without scanning the full range.
    /// </remarks>
    public override T Get()
    {
        ObjectDisposedException.ThrowIf(_disposed, this);

        for (var i = Volatile.Read(ref _top); i >= 0; i = Interlocked.Decrement(ref _top))
        {
            var key = (_poolId, i);
            if (_cache.TryGetValue(key, out T? item))
            {
                _cache.Remove(key);
                return item!;
            }
        }

        return _policy.Create();
    }

    /// <summary>
    /// Returns an instance to the pool.
    /// </summary>
    /// <param name="obj">The instance being returned.</param>
    /// <remarks>
    /// The instance is stored only when
    /// <see cref="IPooledObjectPolicy{T}.Return"/> accepts it and, when the
    /// instance implements <see cref="IResettable"/>, its
    /// <see cref="IResettable.TryReset"/> succeeds. Rejected instances are
    /// disposed immediately. Accepted instances are pushed onto the stack via
    /// <see cref="Interlocked.Increment"/> and stored in the cache with a
    /// post-eviction callback that disposes the instance when the cache drops
    /// it.
    /// </remarks>
    public override void Return(T obj)
    {
        ObjectDisposedException.ThrowIf(_disposed, this);

        if (obj is null)
            return;

        if (!_policy.Return(obj) ||
            (obj is IResettable r && !r.TryReset()))
        {
            (obj as IDisposable)?.Dispose();
            return;
        }

        var i = Interlocked.Increment(ref _top);
        _cache.Set((_poolId, i), obj, _options);
    }

    /// <summary>
    /// Removes all cached instances from the pool without disposing the pool
    /// itself.
    /// </summary>
    /// <remarks>
    /// Atomically resets the stack pointer and removes every cache entry in the
    /// range that was occupied. Useful for a full flush between game levels or
    /// similar reset boundaries.
    /// </remarks>
    public void Clear()
    {
        ObjectDisposedException.ThrowIf(_disposed, this);

        var last = Interlocked.Exchange(ref _top, -1);
        for (var i = 0; i <= last; i++)
            _cache.Remove((_poolId, i));
    }

    /// <summary>
    /// Gets the approximate number of instances currently cached in the pool.
    /// </summary>
    /// <remarks>
    /// This is an estimate based on the stack pointer. The actual count may be
    /// lower because <see cref="IMemoryCache"/> may have evicted entries
    /// without updating the pointer.
    /// </remarks>
    public int Count
    {
        get
        {
            var c = Volatile.Read(ref _top) + 1;
            return c >= 0 ? c : 0;
        }
    }

    /// <summary>
    /// Disposes the pool, clearing all cached instances.
    /// </summary>
    /// <remarks>
    /// The pool does not own the <see cref="IMemoryCache"/> (it is owned by the
    /// container), so only the pooled instances themselves are released. Each
    /// evicted entry triggers the post-eviction disposal callback registered in
    /// the constructor.
    /// </remarks>
    public void Dispose()
    {
        if (_disposed)
            return;
        Clear();
        _disposed = true;
    }

    private static MemoryCacheEntryOptions WithEvictionCallback(MemoryCacheEntryOptions opts)
    {
        opts.RegisterPostEvictionCallback(static (_, value, _, _) =>
            (value as IDisposable)?.Dispose());
        return opts;
    }
}